/*
 * backtrace.h
 *
 *  Created on: Dec 28, 2010
 *      Author: yossi
 */

#ifndef BACKTRACE_H_
#define BACKTRACE_H_

#include <stdio.h>

typedef struct backtrace backtrace_t;

/**
 * Create a backtrace from the calling location.
 *
 * @return: Backtrace object.
 */
backtrace_t *backtrace_create(void);

/**
 * Destroy a backtrace and free all memory.
 *
 * @param bckt Backtrace object.
 */
void backtrace_destroy(backtrace_t *bckt);

/**
 * Walk to the next backtrace line information.
 *
 * @param bckt Backtrace object.
 * @param address Filled with backtrace address.
 * @param file Filled with a pointer to the source file name.
 * @param function Filled with a pointer to function name.
 * @param lineno Filled with source line number.
 *
 * NOTE: the file and function memory remains valid as long as the backtrace
 * object is not destroyed.
 */
int backtrace_next(backtrace_t *bckt, unsigned long *address, char const ** file,
                   char const ** function, unsigned *lineno);

/**
 * Print backtrace to an output stream.
 *
 * @param stream Stream to print to.
 */
void backtrace_print(FILE *stream);

#endif /* BACKTRACE_H_ */
